<?php
// $Id: Ticket.interface.php 73 2007-02-12 03:45:43Z tswicegood $

/**
 * This file contains {@link Ticket} which is part of the PHP Content Repository
 * (phpCR), a derivative of the Java Content Repository JSR-170,  and is 
 * licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */


/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/phpCR.library.php');

phpCR::loadInterface('Repository');
phpCR::loadInterface('Credentials');


/**
 * Through this interface all access to the content repository occurs.
 *
 * Returns by {@link Repository::login()} upon success.
 *
 *
 * Both level 1 and 2 implementations must implement this interface, though
 * in level 1 some methods will throw an
 * {@link UnsupportedRepositoryOperationException} (see the method-by-method
 * descriptions).
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface Ticket
{
   /**
    * Returns the {@link Repository} object through which this {@link Ticket} 
    * was acquired.
    *
    * @return  object
    *  A {@link Repository} object.
    */
    public function getRepository();
    
    
   /**
    * Returns the {@link Credentials} object that was used to authorize the
    * issue of this {@link Ticket}.
    *
    * @return object
    *   The {@link Credentials} of this {@link Ticket}.
    */
    public function getCredentials();
    
    
   /**
    * Returns the {@link Workspace} attached to this {@link Ticket}.
    *
    * @return object
    *   A {@link Workspace} object.
    */
    public function getWorkspace();
    
    
   /**
    * Returns new {@link Ticket} in accordance with the specified (new)
    * {@link Credentials}.
    *
    * Allows the current user to "impersonate" another using incomplete
    * {@link Credentials} (perhaps including a user name but no password, for
    * example), assuming that their original {@link Ticket} gives them that 
    * right.
    *
    * Throws a {@link LoginException} if the current {@link Ticket} does not
    * have sufficient rights.
    *
    * @param object
    *   A {@link Credentials} object
    * @return object
    *   A {@link Ticket} object
    *
    * @throws {@link LoginException}
    *   If the current ticket does not have sufficient rights.
    */
    public function impersonate(Credentials $credentials);
    
    
   /**
    * Returns the root {@link Node} of the workspace.
    *
    * The root {@link Node}, "/", is the main access point to the content of the
    * {@link Workspace}.
    *
    * @return object
    *   The root {@link Node} of the {@link Workspace}.
    *
    * @throws {@link RepositoryException}
    *   If an error occurs.
    */
    public function getRootNode();
    
    
   /**
    * Returns the {@link Node} specifed by the given UUID.
    *
    * Only applies to {@link Node}s that expose a UUID, in other words, those 
    * of mixin {@link NodeType} mix:referenceable.
    *
    * @param string
    *   A universally unique identifier (UUID).
    * @return object
    *   A {@link Node}.
    *
    * @throws {@link ItemNotFoundException}
    *   If the specified UUID is not found.
    * @throws {@link RepositoryException} 
    *   If another error occurs.
    */
    public function getNodeByUUID($uuid);
    
    
   /**
    * Returns the {@link Node} at the specified absolute path.
    *
    * @param string
    *   An absolute path.
    * @return object
    *   A {@link Node}.
    * @throws {@link PathNotFoundException}
    *   If the specified path cannot be found.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function getNodeByAbsPath($absPath);
    
    
   /**
    * Validates and (if validation succeeds) persists all changes made through
    * this {@link Ticket} since the last {@link save()} or {@link revert()}.
    *
    * Constraints mandated by {@link NodeType}s are validated on {@link save()}.
    * If validation fails a {@link ConstraintViolationException} is thrown and
    * the state of the transient storage is left unaffected. If validation 
    * succeeds then all pending changes are persited and the transient change 
    * cache is flushed.
    *
    * The {@link save()} method allows a {@link Node} to be in a temporarily 
    * invalid state while it is being "built", that is, while it is having 
    * properties and child {@link Node}s added to it. Once it is in a 
    * consistent state it can be saved.
    *
    * An {@link AccessDeniedException} will be thrown if an attempt is
    * made to {@link save()} changes for which the current user does not have
    * sufficient access rights.
    *
    * An {@link ActionVetoedException} will be thrown if a 
    * {@link VetoableEventListener} vetoes one of the changes being saved.
    *
    * If {@link save()} succeeds then the all changes are removed from the cache
    * of pending changes in the {@link Ticket}.
    *
    * @throws {@link ConstraintViolationException}
    *   If any of the changes would violate a constraint as defined by the
    *   {@link NodeType} of the respective {@link Node}.
    * @throws {@link AccessDeniedException}
    *   If the current {@link Ticket} does not have sufficient access rights to
    *   complete the operation.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    * @throws {@link ActionVetoedException}
    *   If a {@link VetoableEventListener} vetoes one of the changes being 
    *   saved.
    */
    public function save();
    
    
   /**
    * Discards all pending changes made through this {@link Ticket}, that is, all
    * changes made since the last sucessful {@link save()}.
    *
    * @throws {@link RepositoryException}
    *   If an unexpected error occurs.
    */
    public function revert();
    
    
   /**
    * Deserializes an XML document (in system view form or 
    * document view form) and adds the resulting item subtree
    * as a child of the {@link Node} at parentAbsPath. Requires a
    * {@link save()} to persist the changes.
    *
    * The deserialization mechanism must take into account the
    * {@link Property} jcr:uuid in order to reconstruct hard links
    * across serialization/deserialization cycles.
    *
    * If {@link NodeType} restrictions prevent the addition of the subtree to
    * the {@link Node} at $parentAbsPath, a 
    * {@link ConstraintViolationException} is thrown.
    *
    * If the XML string provided is not a valid JCR system view 
    * XML document then an {@link InvalidSerializedDataException} is thrown.
    *
    * If the user does not have sufficient access rights to write the
    * deserialized {@link Node}s and {@link Property}s, then an
    * {@link AccessDeniedException} is thrown on {@link save()}.
    *
    * <b>PHP Note</b>: Java requires that $in be an InputStream.
    * As PHP doesn't do this, it is only required that an XML string be based
    * in.  At the option of the implementing developer, $in could
    * also be made to allow for a
    * {@link http://us3.php.net/manual/en/ref.dom.php DOM XML} or in the case 
    * of an XML document without attributes a
    * {@link http://us2.php.net/manual/en/ref.simplexml.php SimpleXML} object.
    * At all times, however, this method should be capable of accepting a
    * string as $in, in addition to any implementation-specific
    * capabilities.
    *
    * <b>PHP Note</b>: In the Java specification, there is another 
    * {@link importXML()} that requires only the first parameter.   It relies
    * on the org.xml package in Java to operate, so it has been
    * excluded from {@link http://www.phpcr.org phpContentRepository}.
    *
    * @param string
    *   The absolute path of the {@link Node} below which the deserialized 
    *   subtree is added.
    * @param string
    *   The string from which the XML to be deserilaized is read.
    *
    * @throws {@link PathNotFoundException}
    *   If no {@link Node} exists at $parentAbsPath.
    * @throws {@link ItemExistsException}
    *   If an item by the same name as the newly imported root {@link Node}
    *   already exists.
    * @throws {@link ConstraintViolationException}
    *   If {@link NodeType} restrictions prevent the addition of the subtree to
    *   the {@link Node} at $parentAbsPath.
    * @throws {@link InvalidSerializedDataException}
    *   If the serialized data being input is not a valid JCR 
    *   system view XML document.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function importXML($parentAbsPath, $in);
    
    
   /**
    * Within the scope of this {@link Ticket}, rename a persistently registered
    * namespace URI to the new prefix.  
    *
    * The renaming only affects operations done through this {@link Ticket}.
    * To clear all renamings the client must acquire a new Ticket}.
    *
    * If the specified $uri is not among those registered in the
    * {@link NamespaceRegistry} then a {@link NamespaceException} is thrown.
    *
    * @param string
    * @param uri a string
    *
    * @throws {@link NamespaceException}
    *   If specified uri is not registered.
    */
    public function setPrefix($prefix, $uri);
    
    
   /**
    * Returns all prefixes currently set for this {@link Ticket}.
    *
    * This includes all those registered in the {@link NamespaceRegistry} but
    * not over-ridden by a {@link Ticket::setPrefix()}, plus those
    * currently set locally by {@link Ticket::setPrefix()}.
    *
    * @return array
    */
    public function getPrefixes();
    
    
   /**
    * For a given $prefix, returns the URI to which it is mapped 
    * as currently set in this {@link Ticket}.
    *
    * If the prefix is unknown a {@link NamespaceException} is thrown.
    *
    * @param string
    * @return string
    *
    * @throws {@link NamespaceException} 
    *   If the prefix is unknown.
    */
    public function getURI($prefix);
    
    
   /**
    * Releases all resources associated with this {@link Ticket}.
    *
    * Calling this method is not mandatory since a good implementaion should 
    * automatically timeout anyway. However, when more precise control over 
    * resource allocation is needed this method can be used.
    */
    public function logout();
}

